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ABSTRACr 

A Lisp prcily printer is presciilcd vvhicii makes il easy for a user to control tlic format ofllic 
output produced. TliC printer can be used as a general niechanisni for printing data structures 
as well as programs. Il is divitlcd into two parls: a set of formatting functions, and an output 
routine. The user specifics how a particular type of object siu^tild bo fornuUlcd by creating a 
formatting function for the type. When passed an object of lliat l}pc, the ft>rniatting function 
creates a sequence of directions which specify how the object sh^nild be printed if it can fit on 
one line and how it should be printed if it n»ust be i)roken up a^aoss nvtltiple tines. A simple 
tomplale language makes it easy to specify these directions. Based on the line length available, 
die oiitput routine decides what strucUnes have to be broken up across multiple lines and 
produces die actual output following the directions created b) tlic fctrmatting functions. 'ilie 
paper concludes with a discu.^sion of how the pretty pnnting nieihod picscntcd could be 
applied to languages oUicr than Lisp. 
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Introduction 

Most pretty printers arc used solely for formatting program text. 1'hey lypica!ly operate by reading in a 
file of program text and producing a formatted text file as output. In general tliey have built-in knowledge 
specifying how each syntactic structure in the programming language should be formatted and do not give the 
user any significant control over the format of the output produced [I 2, 4-9]. With such a pretty printer, the 
lack of user format control mechanisms is tolerable because in most cases die user cannot dcfme any new 
language constructs and therefore die implementors of the printers can predict in advance all of the structures 
which die printer can encounter (and diough Uiere is no firm consensus on how diesc structures should be 
formatted it is possible to select reasonably acceptable formats)* 

Some pretty printers (such as the I asp printer presented here) are used as part of the programming 
environment to display information to die user radier dian as text llle processors. (Note diat an inherent 
limitiition of sucli printers is that they cannot operate on parts of a program (such <is comments) which appear 
only in text files.) These pretty printers do not have to be relegated solely to prindng programs. They can be 
just as useful for printing data structures. If a pretty printer's use is extended to user defined data structures, 
user format control mechanisms become esseniial because it is no longer possible to predict what structures 
will be encountered. 

Extending preUy printers to deal with data is important because user defined data structures are central to 
almost any program. When debugging a program, a programmer ncctis lo be able to look at various data 
items. HvQty interactive programming environment supports the display of the simple atomic data values 
supported by the language (such as numbers and strings). However, most environinents are not prepared to 
print out die contents of complex user data structures in any useful way. 

User defined data absuactions are typically implemented by ccmibining together primitive data structures 
(e.g. vectors, record structures, and pointers), A pretty printer can be extended to deal with arbitrary user 
datit abstractions by adding print formats for each basic datii structure, l^or example, record structures might 
be printed as <Jlcldl field! . . . > widi each field printed on a separate line if die structure cannot be printed on 
a single line. Vectors could be printed analogously as \_iteml iteml . . . ]. Pointers could be printed as '0' 
followed by what they point to. Suppose that a user has defined a data abstraction which is implemented as a 
record structure with several fields, one of which is a vector of pointers to records. Using the above default 
formats, an instance of this abstraction would be printed as follows (assuming that several lines had to be used 
to print it). 

ifield 
field 

i%<feld ...> 
Ufield ...> 

. . .> 

Unfortunately, this simple approach is not very satisfutory. The direct display of die underlying datii 
structure which implements i\ data abstraction is not liable to capture die user's idea of what die dat^i 
abstraction means. For example, some components of the data structure may not be very inipoitaiit and 
should not be displayed at all. Other kinds of data structure cumponcms (for examjilc, circular pointers) 
cannot bo displayed literally and must be abbreviated in some way. Alternately, it may be useful to print out 
some addiuonal quantities which, diough not actually in the shucture.. are useful for understanding die 
structure (for example, die names of die fields or derived values cximputed fixmi die field values). 

A collaieral advantage of die rigid output format initially prc^posed is diat it can be built into die reader as 
well as the printer so that it i^ possible (o recreate a data structure by reading in its printed representation tn 
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order to maintain tins readability property when fields are being omitted, abbreviated, and/or added in the 
printed representations for data structures, tlic user must be careful to insure tliat no infornKttion is actually 
being lost, and the reader must be modified to take these special printed representations into account. In Lisp 
prograrnming environments (for example [10]), this kind of reader modification is usually possible tliough not 
necessarily easy. It should be noted that in general it is nnich more imi)ortant to print out a data structure in a 
form which can be easily read and understood by the user than to print it out in a form which can be read by 
the reader. 

Another serious problem with the simple output scheme proposed above is d)at the kind of defluilt 
formatting rules proposed almost never lead to output which is aesthetic, ^rhe visual appearance of a data 
structure has a very important effect on its understandability, Perhaps different delimiters or indentation 
would make the data structure more readable. Perliaps the first two fields are closely related and should 
always be printed on the same line, l^erhaps the structnre as a whole has two quite separate logical parts 
which should always be printed on two lines. 

In order to deal with these problems, it is essential tliat die user be able to control how individual data 
abstractions are to be printed. Ilie pretty primer for I Jsp presented in diis paper allows die user to specify for 
each type of data structure both what components to print, and how these components sliould be formatted. 
If the printer is used as the standard printer, then die user will be able to inspect his data structures and see 
diem printed out aesthetically at all times. 

Pretty printers are typically conceived of as system utilities for displaying information to the user. 
However, a pretty printer can be much more usefid if it can also be used as an output facility which is called 
directly from user programs. The advantage of this is diat it makes available a new paradigm for specifying 
output fV>rmat. 

Most high level languages have facilities for specifying how output is to be formatted on die page (e.g, tlie 
Fortran FORMAT statement). In general, these facilities are oriented toward printijig data structures whose 
shiipe is known in advance on a page whose width is known in advance, There are usually no facilities which 
deal with variability in eidicr the sliape of the data or the width of die page. If eidicr of these has to be 
paiamcterized, dicn the programmer has to wj ite code which computes how each particular data structure 
sliould be formatted. 

Pretty printers are specifically designed to deal widi variability in the data and in the space available. 
vVtien using a pretty printer, instead of specifying a format for die output as a whole, the programmer 
specifies individual formats for each of die intermediate structures which can occur in the oiyect to be 
printed.' These formats do not have to be parucularly concerned with either die line w^idth or how the 
intermediate structures will be combined togedier. When printing a structure, the pretty printer 
automatically combines the individual formats and decides where to insert line breaks and blank space in 
order to make its output fit readably in the space available. 

The sections below describe how a particular Lisp pretty printer (GPRINT) provides for user fonnat control 
and discuss some of the general issues involved. GPRINT \vas originally implemented in 1975 as an attempt to 
improve on an earlier pretty printer implemented by Goldstein [3]. Goldstein's pretty printer is one of the 
few pretty printers which docs include mechanisms providing significant user control over the format 
produced. Unfortunately, (he mechanisms he provides arc at the same time complex to use and not very 
powerful, GPRINT has been rewritten four times most recently in 1981 in a continuing attempt to create a user 
C(nUrollable preUy printcj" with very good human engineering. 

GPRINT is written in Lisp, and was developed in die context of a Lisp programming environment. The 
Lisp language is used in this paper to display parts of the preUy printing algorithm and Lisp lists are used in 
examjiles of how objects are printed, lliis is done because Lisp has several features which make the 
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implementation and explicaiion of a pretty printer particularly easy. However, it should be noted that the 
ideas embodied in GPRINT are not limited to the IJsp domain. In particular, these ideas grow principally out 
of the requirements for a highly interactive programming environment, rather than out of the I.is|) language, 
riic last section of tJiis paper discusses what would be required in order U) implement a similar piWy piinier 
for a programming environment other than Lisp. 

An Example 

Before looking at GPRINT in detail, consider die following example. Suppose a user has defined a data 
abstraction called NAMr:D"FORM witii ibur parts: a rORM, which is some arbitrary IJsp expression; a ROOT, 
which is an identifier associated with the FORM; a SUFFIX, which is used to disambiguate forms which have 
the same ROOT; and a PARENF, which is a circular pointer poiiiting up to the NAMED- FORM data structure which 
contains this one. Together the ROOT and the SUFFIX are a unique name for the FORM. The PARENT links 
make it possible to go backwards from a NAMED-FORM to the NAMED-FORMs containing it 

The function definitions below implement access functions and a constructor function for this data 
abstraction implemented as a list, lollowing common IJsp programming practice, the symbol NAMED^FORM is 
put in the CAR of this list so that instances of the data type can be recognized at run time. 

(defun form (x) (cadr x)) 

(defun root (x) (caddr x)) 

(defun suffix (x) (cadddr x)) 

(defun parent (x) (car (cddddr x))) 

(defun create-nained- form (form root suFfix parent) 
(list •named-form form root suffix parent)) 

If nothing more is said, then NAMED-FORMs will be printed out in the default format for lists as follows: 
(NAMED-FORM (f A B) ARG 1 . . . ) 

lliere arc several problems with this. Mrst, diere is no good way to print die circular parent pointer (it is 
elided as " . . . " above), t'.ven if some mechanism is used to keep the print form finite, it will probably be too 
large to be readable. Second, the CAR of the list is important for computational reasons but it is not a logical 
part of die structure. One might well consider that seeing it piintcd out is a distraction. Third, the way the 
remaining three parts of the structure cU'e printed out docs nothing to indicate their logical roles in the 
structure. As a result, it is hard to sec what is what. 
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Hic following example shows one way in which NAMfiD-FORMs could be more aesilietically displayed. 
ARGl: (+ A B) 

llic FORM is printed out preceded by a tag formed by printing the ROOT and SUFFIX as a single unit 
followed by a colon. Note that you would not want to store the ROOT and the SUF FIX as a single unit because 
it is computationally expensive to break them apart. However this is easy for your eye to do. The PARENT 
pointer is not printed at all. 

The following format definition could be used to specify to GPRII\IT that MAMED-FORMs should be printed 
out in the above way. The expression (DEFUN (.vjv///;^;/ :GFORWAt} (arg) body) defines the body as a 
formatting function which will be used to t()rmat lists witli tlic indicated symbol as tlieir CAR. When passed 
such a list, tlic function creates a sequence of formatting instructions specifying what should be printed 
corresponding to the list. Formatting functions can be quite complex. However, in this example, the 
formatting function simply selects three of ilie components of the data structure and calls the n^inction GF 
(short for GPRINT- FORMAT) in order to create the formatting instructions. 

(defun (named -form :Gformat) (x) 

(GF "{2 * * ':' - *}" (root x) (suffix x) (form x))) 

The fimction (GF template argl arg2 . . . ) creates a sequence of formatting instructions for its argutiicnts 
based on directions specified by the template, (Templates are discussed in detail below.) The template in this 
example can be understood as follows: The { and } specify that the components betwccu them should be 
ucatcd as a single logical unit when they arc primed out. The 2 after the { specifics that an indentation of 2 
should be used inside this structure if it has to be broken up across multiple lines. The three *s show where 
the three components of tlic data structure should be |)rinted. The ' : ' specifics that a colon should be 
printed after the SUFFIX. Finally, the - specifies a conditionalline break. If the whole structure will not fit 
on one line, then a line break will be inserted at that point. Otherwise a space will be printed. 

It is important to realize that the format does not just specify how an individual NAMED- FORM should be 
printed in isolation. It is used iis part of the specification of how complex data structures containing 
NAMED- FORMS should bc printed. For example, a list of two NAMED- FORMs would be printed as follows: 

(ARGl: (+ A B) 
CALLER3: (- (+ A B) C)) 

Mhc example assumes that in order to fit the structm^e into the space available (or printing, It had to be 
broken up across two lines. Hie outermost set of parentheses and tlie fact that the tvv(y NAMED-FORMs are lined 
up vertically is controlled by the standard format for lists of data. The individual iNlAMED- FORMS arc formatted 
as specified above. 
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The Basic Algorithm 

The central feature of the algoritlirn used by GPRINT is that t!ic pretty piiiUing process is divided into two 
parts as shown hi Figure 1. 'llie formatting routine takes in an object and creates a sequence of formatting 
instructions specifying what to print. These instructions specify how each part of the object is to be printed if 
it will fit on one line, and how it should be printed if it must l:je broken up across multiple lines, I'his 
information is passed to tlie output routine as a sequence of entries in a queue. The output routine operates 
as a coroutine processing the queue entries as they are created. It decides how to fit things into ihe actual 
space available and then prints them. 



OBJECT - — > 



FORMATTING 
ROUTINE . 



--> QUEUE - — > 



OUTPUT 
ROUTINE 



-> TEXT 



./--% 



Figure 1 : Architecture of the basic pretty printing algoridim. 

Hie imptntance of dividing the algorithm into two parts conies from the fact that it allows a complete 
separation between format sj)ccificcition and the output computation. 1 he output routine is complex and 
comptiUiUon intensive. 1 aken separately, it can be designed to be efllcient without compromising the need 
for the fonnatting process to be as clear and simple as possible. Similarly, when designing the form<uting 
routine and the user format control mechanisms it is possible to concenlrale on providing a powerful and 
convenient interface to the user. 

The basic algorithm described above has Ix'cn independently developed by several peo]ile[4, 7] in 
addition to the audior. However, the formatting routines in these other pretty printers are very primitive, 
'fhcy include only a small set of canned formats and do not allow for user format control. In [7], Oppen gives 
a lucid description of the way tiic output routine operates. I hs discussion centers on die fact that if the 
lookahead used by the output routine when processing queue entiles is appropriately limited, then the 
computadon time required by the output routine is linear iii the numl)er of queue entries created by the 
formatting routine. The only difference between his output routine and GPRlNT's output routine is tliat 
GPRINT's queue entries are more general. This paper focuses on the unique aspect of GPRINT - the way the 
formatting process allows for user format control. 
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lltc Structure of the Formatting Routine 

The structure ol'ilic forniatling routine is based on the idea ttiat any object to be printed by GPRINT ciUi be 
viewed as a directed graph where each terminal node is a primitive data object (such as a number or a symbol) 
and each non-terminal node is a composite data structure (such as a list or array). The formatting routine is 
organi/ed around a central dispatching function (GDISPATCH). At each node, GDISPATCH selects and caJls an 
appropriate formatting function based on various featines of die node (sudi as its data type). 1^he formatting 
function takes die node as its argument and t)ushcs entries onto the queue which specify what to print and 
how it should be formatted, I'ypically, formatting functions call the dispatching function recursively in order 
to format the composite components of the node. 

Consider the following simplified version of GDISPATCH. ^fhis version of GDISPATCH assumes that tlic 
item to be formatted must be cither a number, a symbol, a string or a list. It first tests the data type of tlie 
item, [f it is not a list then ATOM - rORMAT enters it directly into the queue as something to be printed out. If 
the item is a list dien GDISPATCH looks at the CAR of the list in order to pick a specific formatting liincti(m to 
call. Tlie association between list CARS and formatting functions is recorded by storing the function as the 
:GFORMAT property of the CAR. 

(dofun Gdispatch (x) 

(cond ((not (listp x)) (atom-format x)) 

((not (symbolp (car x))) (funcall Gnon-symbol-car-format x)) 
((get (car x) ' iGformat) ) (funcall (get (car x) 'iGformat) x)) 
((fboundp (car x)) (funcall Gfn-format x)) 
(T (funcall Gsymbol -car-format x)))) 

If there is no special formatting function for a list then GDISPATCH uses cither a default format for 
function applications or a formatter for data lists (these formatters are discussed furdier below). These default 
formatters arc stored in special variables so thai they can be easily modified by the user. In a I.isp system 
there is no delinitive way to distinguish Ihe representaiion of a function call from oUier kinds of list data. As a 
heuristic, GDISPATCH looks to sec whether the CAR of the list is tlie name of a currently defined function. 

The actual version of GDISPATCH used by GPRIMT is much more general than die one presented bere. 
First, it can dispatch on additional features of a list other dian its CAR. SccoikI you can specify a specific 
format to use when calling GPRIMT which will override any dispatching. Third. GDISPATCH dispatches on 
many other data types as well as lists (for example, arrays). Tlic user formal control mechanisms described 
here are extended so that they arc applicable to diese other data types. This is discussed in more detail below. 

An important Uiing to keep in mind about formatting functions is diat diey do not print anything - rather 
they specify a set of directions to be followed wlicn GPRINT prints an object of die associated type. In order to 
print soittctliing you call the function GPRINT. It calls GDISPATCH which calls formatting functions which 
create queue entries which are interpreted by die output routine in order to detennine what to print, (t is die 
output routine which actually does the prindng. 

How The Queue Entries Specify Formatting Options 

In order to ftdly understand how formats are specified, it is important to undeistand the entries which are 
pushed onto the queue. These entries are designed to be a concise language for spvxifying formatting options. 
The entries encode two pieces of information: what should be printed if an object can be printed on a single 
line, and what line breaks and indent;Uion should be used if the object will not fit on one line. The following 
t.tble descnbcs die basic queue entries. 
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* literal' - Print tlie literal text between the apostrophes in tlie output. 

^n - (Underscore) Print ;; {(Icfault 1) spaces in the output. Ihc argument can be negative in which case 
the printing point moves left but only if there is sufficient blank space to back up over. 

{ri }- These two entries mark die beginning and end of a group of queue entries which form a 
substructure in the output. This substructure is treated as a single unit when decisions about where 
to insert line breaks arc made. The number following the open bracket specifies how much the 
indentation should be increased while printing items inside the substructure when they will not fit 
on a single line. It can be omitted in which case it defauhs to die sum of die lengths of the first three 
things printed in the subslmcture. 

+// - (Plus) 11iis specilies a change in indentation. 1'hc indentation level in the current substaicturc is 
incremented by // (default 1) which can be negative. 

-//-(minus) A cojulitional tine break. Put a line break in the output if the staicUu'C immediately 
containing this entry cannot be printed on a single line. Olhcrwise, print n (default 1) spaces in the 
output. 

! - Always put a line break here. 

As an example of how formatting information is encoded in queue entries consider the NAMm'-F0Rf4 
example used above. When GPRINT is used to print the list (NAMED-FORM (+ A B) ARG 1 . . . ) the 
formatting routine calls the specially defined formatting function (reproduced below). 

(defun (named-form :Gformat) (x) 

(GF "{2 * * ':' - *}" (root; x) (suffix x) (form x))) 

Based on the template, the call on Q\' creates the following queue entries (assuming for simplicity in this 
example that (+ A B) is formatted as a single atom). 

{2 'ARG' M' •:' - '(+ A B)' } 

The output routine processes these queue entries as they are created. It lets Uio entries corresponding to a 
structure collect in the queue until it can determine whedicr or not there is enough room to print die structure 
on a single line. If die available space is long enough then the eniirc structure will be printed on a single line 
as follows: 

ARGl: (4- A B) 

If there is not enough room then tlic structure will be broken up. The - queue entry indicates that in this 
case a line break should he inseri:ed before (+ a B). Ilic indentation increment specifics tha.t the indcnUUion 
should be increased by two after the line break. 

ARGl: 
(+ A B) 

Jf diere is not enough room to print the two line form, then Uicre is no way U> print out the structure which 
is consistent with the queue entries. I'his is an example of ihojiniie line length problem. Pretty printers in 
general mi^kv from this problem and there is no simple solution to it. However, die problem is usually not 
severe as long as the Hue length available for printing is several times larger than tlic largest indivisible item 
which must be printed on a single line. GPRINT has a number of built-in features (discussed below) which try 
to ameliorate this problem by keeping the indentation small in order to maximize the line Icngtli available. 
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Fomiatting f einplates 

Queue entries arc created exclusively through the use of the function {GT (emplalear^l arg2.,.). GF 
matches its template against zero or inore arguments and produces a series of queue entries, Rach template is 
a string built up out of formatting codes. There arc two sets of codes. The first set corresponds exactly to the 
queue entries described in the last section (i,c: 'literal^ ^ti {n }, +//, -//, and I). The second set of codes 
specifics how the template is to be matched against the arguments to be printed. These are described in the 
table below: 

* - Call GDISPATCH to determine how to format this object. If it is an atom then this creates a literal 

queue entry for it. For example, (GF >" 'ARC) is the same as (GF "'ARG'"). 
I ' Ignore the corresponding object 

Isublemplaie^ - 1'hc part of the object being formatted whidi corresponds to this part of the template 
must be a list. It is decomposed into its elements. The template l)etween die square brackets 
specifies how these are to be formatted. For exauiple, (GF "{*_[*^*]]" *(1 (2 3))) is tlic 
same as (GF "♦_'»•_*" 1 2 3). Processing of a subtcmplate between [] terminates immediately as 
soon as the corresponding list is exhausted. V'or example, (GF "[♦':'*]" ' ( 1) ) is the same as 
(GF %" a) and not (GF %' : •" 1). The [] codes have meaning only to GF and do not by 
themselves create any queue entries. 

. - (l^eriod) Valid only inside []. It specifies tliat the next item is the whole sublist left to pr(x:css by [] 
rather tlian its CAR. ]n)r example, (GF "[*^.*]" '(1 2) ) is tJiesameas (GF "*_'!." l '(2)), 

< > -This is used inside of [] to specify a template for a list of unknown length. The part of tlie 
template between dic angle brackets is taken ds repeating indefinitely, creating a subpattern of 
infinite length. Iu)r example, "[<*_>]" is the same as "[*^*-~.*^*-^*-->*~.*~- • - ]"• 

(// suhtenip/ale) "'Vhh is an abbreviafion lor {// ' ('[suhicmp/afey )'}, This combines together 
three ideas. First, it specifies that the list should be treated as a single structure in the output. 
Second, it specifies that parentheses should be printed as delimiters around tlie list. Third, it 
specifies diat die list should be decomposed using the subtemplate to specify how its components 
should be formatted. Ihis format code is a useful abbreviation because many list Ibrmats share 
these ideas. 

The number after the open parenthesis specifics the indcnt^ition increnient to use in die 
substmcturc. It can be omitted in which case it defaults to the sum of the lengdis of the first Uiree 
entries in the substructure, hi this case the first entry is alw^tys an open parenthesis. 1 ypically the 
second entry will be die first item in die list and Uie third one will be some amount of blank space 
after die first item. 

# ' Tliis can be used in place of an argument to any formatting code (e.g. ^, {}, ( ), +, or -). It specifies 
that the vahie is to be taken from the next input to GF. For example, (GF '" A'^j^'B* " 6) specifies 
that 6 spaces should be printed out between the A and tjie B. 

blank^ - White space can be inserted into a template to give it added readability. It has no meaning in 
the template. 

Consider again the simple template {''{2 * * • : • - >^}") used in the examples above. The diree >*'S 
match against die three arguments to GF causing G(3ISPATCH to be called on each one in turn. The rest of the 
format codes dirccdy specify queue entries. 
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Simple Fornicitting Functions 

Ihis section continues the i)rcsentalion of formatting templates by discussing several st^indard IJsp 
program formats. In GPRINT the user fonriat control mechanisms are used to specify all of the standard 
program formats. This adds greatly to the clarity of the pretty printing algorithm by separating tlic format 
specification from the rest of the algorithm. It also makes it possible for the user to modify the way programs 
are printed by changing the standard formats. It should be noted that in Lisp, programs arc represented as 
lists and are treated just like any other data object. All the mechanisms which allow the user to control the 
format of program lists can be used to control the format of data structures implemented as lists. 

Lisp function applications are traditionally formatted so that they are printed on a single line or, if there is 
not enough room, so that the arguments are lined up vertically one to a line, 'j'he following function is used as 
the default value of the variable GFN- FORMAT which controls how function applications are formatted, llic 
example printout shows how a function apj)lication looks when it has to be printed on luore than tme line. 

(defun :Gfn-format (x) (GF "(*_ <*->)" x)} 
(LIST y 

The template matches against the list as a whole, pjinting parendieses around it in tlie output. I1ic 
indentation increment is left unspecified so that it will default to the length of the function name plus two 
(one for the open piircnthesis and one for the space printed after the function name). This causes the 
arguments to line up one under the other. After the function name is printed out followed by a space, the 
repetitive portion of the template specifies a conditional line break after each argument in the function 
application. Note diat GO I SPAT CH is called (via the * format code) in order to detennine how to format each 
argument. 

Lisp assignments arc typically forniatled so that each successive vaiiable/value pair appears on a separate 
line. This can be specified by using the 1 format code in a Icmplate as shown. The following DEFUN sets up a 
formatting function which specifies that this format should be used for lists which begin with the atom SETQ. 

(defun (setq :Gformat) (x) (GF "(*_ <*_*1>)" x)) 

(SETQ Y 1 
1 2) 

Hiis template is very similar to the one for function applications. T he only difference is diat the repeating 
portion of the template specifics diat the arguments are to be formatted in pairs widi a mandatory line break 
after each pair. T1iis forces each pair to appear on a separate line even when die entire SETQ could fit on a 
single line. Note that there is no line break before the close parcntJiesis after the last pair because processing 
in a subtemplate for a list slops immediately as socm as the elements of the list arc exhausted. 



^^^\ 
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The LET construct is used to bind a gr{)tip of variables to initial values and then execute a sequence of 
statements in this environment, 'jypically, the variable binding pairs arc printed one to a line and tlie 
statements are printed one to a line. A small indentation is used for the statements in order to visually 
dilTcrcntiate them from tlie bound variable pairs and in order to keep the total indentation small. 

(defun (let ;Gformat) (x) (GF "(2 ♦^ (t <*!>) <-♦>)" x)) 
(LET ((Y 1) 

(CONS Y Z)) 

11ie template specifies an explicit indentation of 2 for the statements in the LET. After the atom LET itself 
is printed out, a subtemplatc specifics how the list of bound variable pairs should be formatted. Mere an 
explicit indentation of 1 is used so that dicy will line up one under the other. A I format code is used to force 
each one to appear on a separate line, fhc final repetitive portion of the template as a whole specifics a 
conditional line break before each statement in the LfiT. Note that if there is only one bound variable pair 
this allows the let as a whole to be printed on a single line if it will fit 

Conditional expressions are formatted so diat each clause of the conditional apj)cars on a separate line, 
F^ach clause is composed of a predicate followed by a sequence of stiitcments. If a clause will not fit on a 
single line, the predicate and statements are printed out one under the other. 

(defun (cond :Gformat) (x) (GF "(*_ < (i <*->) i > )" x)) 

(COND ((MINUSP Y) 
(- Y)) 
(T Y)) 

In this template the repetitive portion of die template as a whole consists of a subtemplatc for the clauses 
and a I Jbrmat cr>dc which forces each clause onto a separate lino. Ihe subtemplatc s|)ecifics an explicit 
indentation of 1 and a conditional line break after each expression in the clause. 

1lic following formatting function for MULTIPLF-VALUF-BIND illustrates the use of the + format code. In 
order to highlight the difference between them, the form which returns tJic multiple values is printed at an 
indentation of 4 while die statements which use die bound values are printed at an indentation of 2, The 
indentation is initially specified as 4. I'he subtemplatc then prints out the list of bound variables. After dic 
muUiplc value returning form is printed the indentation is decremented by 2. The repetitive portion of die 
template then prints out the remaining forms one to a line at an indentation of 2. 

(defun (inult1p1e-value-bind :Gforinat) (x) (GF *'(4*_ (<♦,.>) -* +-2 <-*>)" x)) 

(MULTIPLE-VALUE-BIMD (SYMBOL ALREADY-THERE-P) 
(INTERN STRING) 
(COND (ALREADY-THERE-P (ERROR "Symbol already there: *' STRING))) 
SYMBOL) 
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As a final example, con^^idcr the function QUOTE. A list which begins with the atcMii QUOTH is not printed 
with parenlhcses around it. Rather, the argument to QUOTE is printed out following a '*'". Hie example 
shows the way the list (QUOTE A) is formatted, 

(defun (quote :Gforaiat) (x) (GF "{»'"[i «]}'• x)) 



'A 



llie template sets up a substructure and prints a " ' " (inside of a literal in a template, " ' * " stands for '' ' "). 
It then prints out the argument to QUOTE. Note how it uses the format codes [] and I in order to select out 
this argument. 

More Complex F^ormatting Functions 

A wide variety of formats can be specified using simple formatting functions like tliose above which 
contain v)nly a single call on the function GF. However, these formats arc restricted in several ways. In 
particular, with tliese simple formatting functions it is not possible to vary the format based on the actual data 
values in a structin*e. More complex formats can be specified by taking advantage of the fact that a formatting 
function can contain arbitrary computation. 

bbr example, consider the following way in which the format for NAMED- FORMs could be extended. 
Suppose that the suffix field in a NAMED-FORM is optional and that a value of NIL indicates that there is no 
suffix. In this case we do not want to print the suffix at all. The example shows how the list 
(NAMED-FORM (f A B) ARG NIL ,..) should be printed. 

(defun (named-form ;Gformat) (x) 
(GF "{2 *" (root X)) 

(cond ((not (null (suffix x))) (GF "♦" (suffix x)))) 
(GF •" ; •'♦}" (form x))) 

ARG: (+ A B) 

In the above format definition die single template used in the format definition in the beginning of this 
paper is broken into three pieces. A conditional test is inserted so tJiat printing of the suffix only occurs when 
it is non-null. The { and } indicaUng the beginning and end of the substructure of queue entries being 
created are specified in separate calls on GF. This is a common occurrence and is in contrast to [] 
(and therefore ( )) which must be properly nested in a single call on GF. 

01 all of the formats in this paj^er, tliis is perhaps the best example of the way GPRINT is typically used. 
Some simple templates are combined with some simple computation in order to define a fiexible and 
aesthetic fonnat for a data object. ; 



/^""^^ 
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Block Form and I abular Form 

In order to save space, long lists of data are often formatted in block form where as many items as possible 
are put on each line. The language which is used to create formatting templates has two format codes which 
arc useful for specifying this kind of fonnat. 

. n ' (Comma) A line break is inserted Ivcre if and only if the structure immediately following this code 
will not fit on the qa\A of the current line. Otherwise // (deiault I) spaces are printed. 

; n ' (Semicolon) 1his is the Siime as the co^nma format except that additional spacing is inserted so that 
tl)e items printed out line up in a fibular fashion. 1 he argument ;/ specifies wliat spacing to use 
between the columns in the tabic. If it is omitted a default value will be chosen by the output 
routine based on the lengths of the items to be printed out. 

The following formatting function can be used to print out a list in block form. 
(dofun :Glblock (x) (GF "(I <♦,>)" x)) 

(ORANGE PEAR (RtT) APPLE) GRAPEFRUIT 
(HAWAIIAN PINEAPPLE) BANANA 
CANTALOUPE POMEGRANATE TANGERINE) 

llierc is a problem with printing lists of data in block format. If the elements of a list arc themselves lists 
with a depth of greater than one, then the output is not very aesthetic because it is not easy to identify the 
elements of the top level list, hbr example, consider the following list: 

((ORANGE (SELL 3)) (PEAR (BUY 10)) ((RED APPLE) (f3UY 5)) 
(GRAPtFRUlT (BUY 10)) ((HAWAIIAN PINEAPPLE) (SELL 8)) 
(BANANA (SELL 5)) (CANTALOUPE (BUY 4))) 

T he following formatting function uses the semicolon format code in order to print out lists in a tabular 
format. It is used as the default value of tiic special variables GSYMBOL-CAR-FORMAT and GNON-SYMBOL- 
CAR-FORMAT which control how lists of data are printed. This makes the output much easier to read without 
taking up very much more space. 

(defiin rGlTblock (x) (GF "(1 <*;>)" x)) 

((ORANGE (SELL 3)) (PEAR (BtJY 10)) 

((RED APPLE) (BUY 5)) (GRAPEFRUIT (BUY 10)) 

((HAWAIIAN PINEAPPLE) (SELL 8)) 

(BANANA (SELL 6)) (CANTALOUPE (BUY 4))) 

Due to the hci that the output routine uses only limited look ahead, tlie tab size must usually be chosen 
before all of the elements in tlie list have been entered in the queue. As a rcsulL it is not guaranteed to be 
large enough. In this example, the fourth element in the list was not completely entered in \h<t queue at the 
time when it was determined that the list had to be put on moj e than one line. As a result, only the first three 
elemcfits were used to determine the tab size which turned out to be too small to accommodate the fifth 
element. 
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_^^^. Functional Sublemplales 

The following format codes increase tlie llexibility of the templates by tiiaking it possible to call functions 
at different points in a template. 

%f " This specifics that die function/ should be called in order to format die corresponding item. T^he 
end of Ihe function name is delimited by a space. 

$/- (Dollar sign) This command specifies diat GDISPATCH should be called in order to format the 
corresponding item, but thiU die function/ should be passed ti) GDISPATCH as a suggestion of how 
to format the item. As above, die end of die function name is delimited by a space. The difference 
between $/ and %f is that widi $/ GDISPATCH gets control. As a result, if the item is not a list, then 
die function/ will not get used. 

The use of die $ code is illustrated in die following format which block formats a tree at all levels. It is 
capable of formatting trees of arbitrary depdi because it explicidy calls itself recursively. GDISPATCH is called 
at each level of die recursion. As a result, as soon as an atom is encountered, the recursion is terminated and 
die atom is printed normally. 

(defun :Gblock (tree) (GF "(l<$:Gb1ock ,>)" tree)) 

(ONE (TWO THREE) 
((FOUR FIVE) SIX 

SEVEN) 
EIGHT NINE) 

The following formatting fiuiction for PROG uses % so that it can call a subformal (GPROG-rORMAT2) 
^"^^ wUhout GDISPATCH being called. This is necessary so diat die labels (which are atoms) in die PROG will be 

processed by GPR0G-F0RMAT2. Labels are printed loil shiHcd by computing negative arguments for ^. 

(declare (special Gwas-label)) 

(defun (prog :Gformat) (list) 
(let (Gwas-label) 

(GF "(*_$:Gb1ock <%Gprog-'f ormat2 >)" list))) 

(defun Gprog-formatZ (item) 

(cond ((not Gwas-label) (GF "1"))) 
(cond ((atom item) (setq Gwas-label T) 

(GF "_j^*_" (- (1+ (nats1/,e item))) item)) 
(T (GF "*" item) (setq Gwas-label nil)))) 

(PROG (RESULT) 

L (COND ((NULL LIST) (GO THE-END))) 

(SEIQ RESULT (CONS (CAR LIST) RESULT)) 
(SETQ LIST (CDR LIST)) 
(GO L) 
THE'TTID (SETQ RESULT (NREVERSE RESULT)) 
(RETURN RESULT)) 

An important aspect of the last example is the way it interacts with length abbreviation (described below) 

and other standard facilidcs provided by GPRINT. Since length abbreviation is implemented by [], in order 

to get length abbreviation to apply to the formats you write, you liave to use [j. This is an important reason 

for writing it in the form given above rather dian as a single routine containing a loop which decomposes die 

^^'^^^ list itself and creates the con ect format codes. 
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Miser Mode 

GPRINT provides jievcral facilities wiiich help deal with the finite line length problem. The most 
comprehensive of these is a modified form of the miser mode supported by Goldstein's pretty printer [3]. 'Fhc 
point at which miser mode is triggered is ccmtrolled by the variable MISCR-wrDTH (whicir defa^ 40). If 
the line widUi available for printing is less than MISER-WIDTH, then miser mode is triggered, and formatting is 
modified in two ways, l^rst, all indentations inside {} formats are forced to be I no matter what is specified. 
Second, all + formats are ignored so that the indentation remains 1 in each substructure, hi addition to this, a 
formatting command (M) is provided so that the user can specify line breaks which should only happen when 
miser mode is triggered. 

M - A line break is inserted here if and only if the containing structure cannot be printed on one line, 
and the width available for printing is less than MISER-WIDTH. 

-A/ - Crildc) Print // (default 1) spaces in the output. 1Tie argument can be negative in which case the 
printing point moves left if there is sufficient blank space to back up over. 

_A/- (Underscore) Hiis is actually an abbreviation for -//M. It therefore specifies a miser mode line 
break. 

In order to sec how miser mode works, consider the format for MtiLTIPLE-VALUE-BiND reproduced 
below. The example sliows die format wliicli this specifies in miser mode. Tlie indcnuition increment is 
reduced to a constant 1, and the occurrences of _ lead to line breaks when misering. The same effects can be 
seen in the COND. 

(defun (multiple-valuQ-bind :Gformat) (x) {Gf "(4*_ (<'*'^>) -* +-2 <-♦>)" x)) 

(MULTIPLE-VALUE-BIND 
(SYMBOL ALREADY-THERE-P) 
(INTERN STRING) 
(COND 
(ALREADY-THERE~P 
(ERROR 

"Symbol already there: " 
STRING))) 
SYMBOL) 

In order to maintain some of the indcntaUon pattern of MULTIPLE-VALUE-BIND in miser mode, the - 
format code could be used in place of _ and + as shown below. 

(defun (multiple-value-bind :Gformat) (x) (GF "(2*- (<♦_>) - ~2* <-*>)" x)) 

(MULTIPLE-VALUE-BIND (SYMBOL 

ALREADY-THERE-P) 
(INTERN STRING) 
(COND 
(ALREADY-THERE-P 
(ERROR 
^'Symbol already there: " 
STRING))) 
SYMBOL) 

ThroOgh judicious choice of when to use - instead of _ or i-, the user can gain considerable control over 
how a format will look in miser mode, J lowevcr, as can be seen above, miser mode is not particularly 
aesihctic no matici what you do. It exists solely .\s an emergency measure to prevent prinlout from 
overrunning the riglit margin. 



r^-^. 
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Left Shifting of Major Units 

Another way in which GPRINT deals with the finite line length problem is to take logical units ofprograrn 
text {such as LETs, PROGs, and DOs) and shift them left in order to increase die amount of line width available. 
This process is triggered when die line width available for printing is less dian MAJOR -WIDTH {which defaults 
to 40). I, eft shifting is illustrated in the example below. \\\o radical reduction in indentation is very effective 
at increasing die width available. Unfortunately, the nonstandard format reduces readability. This problem is 
ameliorated by the fact that an entire logical unit is being left shifted, not some arbitrary part of the program, 

(defun (let :Gformat) (list) 
(Gcheck-indentation list 
^•(lambda (x) (GF "(2 *41 <*!>)<-*>)" x)))) 

(defun Gcheck-indentation (list format-fn) 
(let ((ind (Gestimate-indent) )) 

(cond ((> (- Glinelen ind) major-width) (GF "%j^" Mst format-fn)) 

(T (GF "U)^'; ---.>.^^.|. p' (~ ind) (- ind 11.)) 

(GF "-v/^^J" (- 5 ind) list forniat-fn) 

(GF "!-#'; ----'--#'1' 1" (- ind) (- ind 11.)))))) 

(DEFUN ROOTS-OF-QUADRATIC (A B C) 
(COND ((NOT (ZEROP A)) 

(LET ((DISCRIMINAMT (~ {* B B) (* 4 A C)))) 
(COND ((PLllSP DISCRIMINANT) 

: — - I 

(LET r(TERMl (- B)) 

(TERM2 (SORT DISCRIMINANT)) 
(TERM3 (* 2 A))) 
(LIST (// (+ TFRMl TERM2) TERM3) 

(// (~ TERMl TERM2) TERM3))) 



)))))) 

Left shifting is implemented by the foniiatting function GCHECK-INDENTATION. 11ic use of this function 
is ilkistrated by the formatting function for LET shown above, li calls GCHECK-INDENTATION passing it the 
simple formatting function for LET which was described in die beginning of diis paper. 
GCHECK-INDENTATION calls the amction GESTIMATE-INDENTATION which looks at the queue of formatting 
commands and determines what indcjitation will be used when printing out the LET. Note that this nuist be 
C{)mputed from die queue because there may be many entries in the queue whicli have not yet been printed. 

If the width available for printing is greater than MAJOR-WIDTH then GCHECK-INDENTATION just calls the 
Ibrmatltng function passed to it. (Note that if die & Ibnnat code was used instead of %, GDISPATCH would 
diink that it was encountering a second (circular) reference to the list being prmtcd and abbreviate it as 
described in die next section). If the width available is less dian MAJOR-WIDTH then GCHECK-INDENTATION 
spaces back to column zero and prints a connnent line which indicates that left shifting is occurring using a 
" I " to show the indcJitation which otherwise would have been used. On the next line, die format spaces back 
to column 5 and calls the formatting function passed to it in order to format the list being printed. Mnally, it 
prints another comment line, Note diat the templates make heavy use of die ^ format code so diat die 
function can compute the appropriate negative spacing. 



/^^"^^s 
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Abbreviation 

GPRINT provides several different abbreviation nmechanisms. First, there is abbreviation based on 
PRINLEVEL and PRINLENGTH as in the standard printer. A "**" is printed for structures which arc too deep, 
and ". . . " is printed in place of the ends of lists which arc too long. The following example shows how the 
list(l (2 (3 (4))) A B C) would appear with PRINLEVEL and PRiNLENGTH both set to 3. 

(1 (2 (3 **)) A ..,) 

There is a separate abbreviation facihty based on die variables PRINSTARTLINE and PRINENDLINE. As 
GPRINT prints, it counts the lines starting with zero for the line die printer is called on. While the line number 
is less than PRINSTARTLINE no actual printing is done. If the line number ever becomes greater dian 
PRINENDLINE, then die printer prints "---" to indicate that truncation has occurred and immedialely stops 
printing and returns nomially. l^.xpcrimentation has shown that setting PRINENDLINE to a relatively small 
number like 4 (while setting PRINLEVEL and PRINLENGTH to NIL) is very useful particularly due to die 
availability of die continuation facilities described below. The example below shows how an example of 
output using these settings. 

(DEFUN ROOTS-OF-QUADRATIC (A B C) 
(COND ((NOT (ZEROP A)) 

(LET ((DISCRIMINANT (- (* B 8) (♦ 4 A C)))) 
(COND ((PLUSP DISCRIMINANT) — - 

Truncation of the output can also be triggered by typing TERMINAL STOP-OUTPUT. TTiis interrupts die 
printer immediately, causing it to terminate returning normally. 

Whenever output is abbreviated due to any of die methods described above, GPRINT remembers the state 
of the printing so diat it can be resumed. Only a single variable is iuaintained so that only die most recently 
abbreviated thing is remembered. If printing was truncated by PRINENDLINE or user intervention, dien it can 
be continued from tlie point ol'lnmcaiion by typing TERMINAL RESUME, 

As an additional feature, you can reprint the last abbreviated thing in full with PRINLEVEL, PRINLENGTH, 
PRINSIARTLINE, and PRINENDLINE abbreviation disabled by typing TERMINAL 1 RESUME. 

As a third kind of abbreviation, if the variable GCHECKRECURSION is T then GPRINT checks (or circularity 
in the ol:>jects it is printing. When a circular reference to an object is encountered, it is replaced in die output 
by ^n or tn. %n is only used in a lisL It is used when the CDR of a list is EQ to an earlier CDR in the same list. 
In diis case // is the number of CDRs separating the two positions, ^n is used in other situations. Here, n 
indicates that n selector operations (CAR, CXR, AREF; but not CDR) were performed between the first 
occurrence of the object and this one. This kind of abbreviation is illusu-ated below. 

the result of (LET ((X '(Y (2 12 3) 4))) 
(RPLACD (CDR X) (CDR X)) 
(RPLACA (CDADR X) X) 
(RPLACA (CDDADR X) (CADR X)) 
(RPLACD (CDDADR X) (CDADR X)) 
X) 

prints as (Y (2 ^2 ai . %z) , %\) 

It is possil^lc (but not easy) to reconstruct the exact slvape of the object from what was printed. However, 
the main purpose is just to print something more readable dum what you would oiherwjsc see. An important 
feature of die way this abbreviation is done is diat it is completely oilhogonal to the rest of the formatting 
pHKCSs so diitt it works no matter what kinds of user formatting functions are written, and no matter what 
kind of data objects are being printed. 
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^,>^ Data Types Other than Lists 

In addition to lists, GPRINT has built in formatters for all of (he standard l.isp data types. Symbols, 
numbers, stiings. and things of random types not specifically discussed below are treated as indivisible atoms 
and printed in the standard ways. 

Named structures, entities, and instances arc printed in one of two ways depending on whether or not Uicy 
know how to format themselves. If Uic object accepts the message :GF0RMAT-SE:LF then GPRINT sends a 
: GFORMAT-SELF message with the object as argument to the object so that it can format itself. 

If the named structure, entity, or instance docs not take a :GFORMAT-SELF message, tJicn GPRINT treats it 
as an atomic object and lets the st;indard printer print it. This makes it possible to use GPRINT on these 
objects without having to write formatters for tlieni. However it should be noted that since they arc treated as 
atomic objects, no formatting occurs inside them no matter how large their print form may be. For example, 
a line break will never be inserted inside one. 

Jf an object is an array (and not a named-structure) it is formatted as follows. GPRINT first checks to see if 
there is a formatting function for the array. The association between formatting functions and a?Tays is 
maintained through a list of functions stored in the variable GARRAY- FORMATTERS. These functions arc just 
like the formatting functions described above except that in addition to creating queue cnlries in order to 
format an ol^jcct, they must also lest to sec whethei" they are applicable to the object. This makes it possible 
for the user to use any kind of applicability test he desires. If tlie format function is applicable it should 
format the object and rettnn T, Otherwise it should take no action and return NIL, A function is set up as an 
array formatter by adding it to die list GARRAY- FORMATTERS. GPRtfJT calls each of these functions in turn 
passing it the object. As soon as one of (hem returns T it slops. II' they all relurn NIL tlien a default formatter 

f^' is used. 

The default array formatter first prints out the array object in the standard way (e.g. as an atom containing 
the type and the address). Next, if the variable GPRINT-ARRAY-CONTENTS is T and the array has only one or 
two dimensions it prints out the contents of the array. The contents are printed ;is a list (for one dimensional 
arrays) or a list of lists (for two dimensional ones). Tabular blocking is used to format diesc lists. 

The kind of arbitrary user specified dispatching supported for arrays is also supported for lists. Functions 
put on the list GLIST-FORMATTERS can be used to associate fonnais with lists when the association is based on 
some feature other than the CAR of the lisL Similarly, functions put on the list GSPECIAL-FORI^ATTERS can be 
used to override all standard dispatching including the initial split based on data type. 

Applicabiiity to languages Other Than Lisp 
It is important to note diat. though the discussion above was cast in the domain of the Tisp language, the 
ideas are substantially programming language independent. It should be possible to use these idea's to 
construct a ttexiblc pretty printer allowing significant user control of format in any programming language 
environinent. 

GPRINT makes it possible for the user to control the format of both programs and data. Of tlicse two 
capabilities, the control over program format is the c;isiest to export to other language environments. Two 
basic things arc required: a representation for program parse trees, and a method whereby die user can 
specify fonnals for non-terminal nodes in these trees, in languages like 1 isp where a data representation for 
parse trees is part of the definition ol' the language, this is the logical choice for the representation. In other 
^-"^ ';'i"g"ages some such representation has to be developed. If the pretty printer is intended to accept program 

text files as input, a parser for the language has (o he implemented if one is not already available. 

There are two basic ways in which user format control can be supplied. One way is to use the same 
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mechanisms which are supphed for specifying data formats by simply applying them to the datii 
representations fbr parse trees. >This is the approach taken by GPRINT. Another apprtiach is to fi)llow the 
suggestion of Oppen [7] and allow the user to specify formats as annotations to the grammar for the 
programming language. l^Yom the point of view of implementation, this approach is essentially identical. 
However, for a language which (uiilike Lisp) has extensive syntax this approach would undoubtedly be 
aesthetically superior since it uses standard grammatical notation in order to camitiunJcatc with the user 
instead of some ad hoc internal representation. 

Using GPRINT's approach to the printing of data in other programming environments is more difficult. 
1lic key issue is being able to obtain data type information at print time. However, before looking at ttiis 
problem in detail consider some other issues. 

The formatting templates described above could be used with any kind of data. The only thing which has 
to be changed is that [] has to be extended so that it can decompose other composite data structures besides 
lists. Logically there is no problem since, in general, any data structure has a default linear ordering for its 
components. I^Tom an implementation standpoint, there is no problem with selecting out components one at 
a time as long as you can determine tjic data type of a given structure. 

The basic dispatching scheme presented above can be straightforwardly extended as long as type 
information can be obtained. It is easy to implement an association between types and formaUing routines so 
that each type could have its own format. Further dispatching on subfcatures of individual types could be 
implemented if desired. 

In a language environment such as Lisp where, in general, complete run time type inforination is available, 
it is triviitl to determine the type of something when it needs to be printed. Unfortunately, in most languages, 
much of the data type information is used only by the compiler and is not available at run time. In a language 
with pure strong typing that makes it possible for the compiler to determine tlie exact data type of every 
variable, the compiler could be straightforwardly modified in order supply the type information needed by 
t!ie dispatclier. One way to do this would be to have the compiler create a table of type information which 
could be referred to by the dispatcher at run time, Altcrnalely, the dispatching needed for individual calls on 
the printer could be perlbrmed at compile time using the compile time type information. In order to make it 
possible for the user to interactively request the printout of various daUi items at run time, the tabular 
approach would be required, just as a dynamic debugger has to have access to tlie compiler's symbol u\bk in 
order to use the programmer's variable names. 

Unfortunately, fcw languages have pure strong typing. Most languages support data types such as union 
types and variant records. Most of the time, this need not be a severe problem because such types are not 
useful unless there is some way for programs to determine what die actual type of a data iterh is. For 
example, the compiler could specify to the dispatcher that a given data item was of a particular union type. 
The programmer would have to supply a decision procedure which could be used by die dispatcher to 
determine the exact type of the data item at run time. 11iis would not be a difficult Uask as long as the union 
type was straightforward and a single decision procedure for the union type could be implemented which 
would work in all situations. 

There are language environments (for example assembler language) which have little nm time type 
information, little compile time type constraints. <md where the user defmed data structures are often of such 
a chaotic nature tliat it would be virtua!l> impossible to write the kind of data type decision procedures 
needed by the dispatcher. In such a situation, the kind of pretty printer presented in this paper would not be 
practical It should be noted that such an uncontrolled environment presents a number of problems much 
more serious than tlie inapplicability of this kind of pretty printing. Currcjit trends have been toward more 
regulari/cd environments which should be able to support a pretty printer like GPRINT. 
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r^^ Conclusion 

GPRINT includes a large number of standard formats and features (such as the ones used as examples 
above). As a result, a user does not have to write any of his own formats in order to get reasonable output in 
ordinary situations. However, no amount of anticipation can satisfy every user. 1lits is particularly true when 
a pretty printer is being used in an interactive programming environment to print data as well as programs, 
and when it is called by user programs as well as by the system itself. 

The principal goal of the design of GPRINT has been to produce a system with good human engineering 
which gives the user powerful focilities for controlling the format of output and which at the same time makes 
the specification of simple formats simple. Two key ideas comprise GPRINT's approach to this problem: the 
basic algorithm chosen, and die existence of multiple levels at which a user can specify formatting 
information. 

llie key features of the algorithm underlie tlie basic simplicity of GPRINT's approach and, at the same 
time, fundamentally limit its scope. The division of die algoridim into two pieces communicating through a 
queue makes it possible to separate the simple parts of the algorithm from the complex ones. The decision to 
use a linear time algoridim in the output routine makes it possible for GPRINT to run with acceptable speed. 
However, it fundamentally limits the kind of formatting decisions which can he made by the output routine. 
In particular, when making its decisions, it can only look ahead a very limited disu\nce. An example of this 
was discussed in die section on tabular form output. 

In line with die limited abilities of die output routine the queue entries are designed so that they encode 
essentially only two fonnatting options for a given structure: how to print it on one line, and how to print it on 
/"-% muUiple lines, (A third miser format is also specified for each structure, however, this format is largely 

implicit and the user does not have very much control over it.) This design is an important basis for the 
understandability of die printer because it presents die user widi a simj)le model of how formatting decisions 
are made. However, one could easily imagine wanting to specify more complex formaUing infiirmation. For 
example, one might want to specify two completely dilfcrent multi-line formats: one to use when there is a lot 
of room available and die other to use when there is only a little space. 

The printer provides three basic levels at which a user can specify formatting infomiation. First, he can 
simply use the default formats supplied with die printer and docs not have to do anything himself. Second, 
he can use simple templates. 1 hcse miike it very easy for him to describe certain aspects of how a structure is 
to be formatted. Third, he can write more complex formatting finictions. 1liis allows him to exercise much 
more control over the format to be used, at die cost of greater complexity. 

nic use of muUiple levels of interaction is a generally useful technique for increasing die 
undcrsumdability and availability of a system to a wide range of users. It makes it possible for users who have 
simple needs to sadsfy them without having to learn very much iibout the system. Users who titke the dmc to 
learn more can then do more. 
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^/^^N Maclisp Compalibilily 

The discussion in the main body ofihis paper is couched in terms of Lisp Machine I Jsp, however, GPRINT 
is substantially Maclisp compatible. Almost everything above applies equally to both versions, I'his section 
discusses the few differences between the two versions. 

I'he I/O in Maclisp is quite different than on the iJsp Machine. The Maclisp version follows all of the 
Maclisp conventions. In particular, you can call GPRINT with a list of files and default output is controlled by 
the variables TYO, ^R, ^W, OUT FILES, etc. 

The compilation environment is somewhat different in Maclisp. GPRINT must be loaded in in order for 
fonnatling functions to comi)ile correctly because GF is a macro. On the Lisp Machine you don't have to take 
any special action in order for this to be the case when you are using GPRINT. In Maclisp you have to make 
sure that it is kuided into the compiler by a DECLARE in any file which defines formats. Also note that in 
Maclisp the functions which take optional control parameters (eg GPRINT, GPRINTI, GPRINC, GLXPLODE, and 
GEXPLODEC) arc Icxprs and need *LEXPR declarations. 

In Maclisp, the functions triggered by TERMINAL STOP-OUTPUT and TERMINAL RESUME are triggered by 
typing control characters. The printer can be stopped by typing ^S. Printing can be resumed by typing '^C 
(/' R in TX3PS20 versions). Reprinting in full is triggered by ^P. In Maclisp these control characters are not set 
up by default. You have to call the function GSET-UP-PRINTER in order to get them defined. Note also that 
in Maclisp, the default symbol for depth «ibbreviation is "?^" instead of"**". 

The Maclisp version of GPRINT supports the formatting of hunks. 1wo basic mechanisms are supplied 
analogous to the ones described for arrays in the main body of the paper. If a hunk is a USRrlUNK which takes 
^^*--^ messages (note that EXTENOs and tlie like are ail USRHUNKs) then GPRINT checks the messages it accepts. If it 

takes the message :GFORMAT"SELF then GPRINT sends a :GFORMAT-SELF message with the object as 
argument to the object so that it can format itself If a USRHUNK does not take a :GF0RMAT'-SELF message, but 
it does Uike a :PRINT~SELF or PRINT message then GPRINT treats tlie hunk as an atomic object and lets the 
standard printer print it. If a USRHUNK does not accept any of tliese messages, then it is treated as an ordinary 
hunk. 

In order to format an ordinary hunk GPRINT first checks to see if there is a formatting function for the 
hunk. TTic user sets up a hunk formatter by adding a function to the list in the variable GHUNK-FORMATTERS. 
T'he purpose of this function is two fold: to test whether it is applicable to a hunk (in which case it returns I) 
and in this case to actually format the hunk. GPRINT calls each of these functions in turn passing it the hunk. 
As soon as one of diem returns T it stops. If diey all return NIL then die hunk is printed by default in the 
normal way (e.g. in parentheses widi die CXRs separated by periods) in block format. 
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Fli nctional Summary 

This appendix describes all of the user functions supported by GPRINT. 

GPRINT objcci ^optiona] stream fowiat level length endline startUne 

This is exactly analogous to PRINT except that it docs pretty printing. The first arguiTient is the object 
to be printed. T\\c second argument specifies die stream to use for output. If it is missing then the 
standard system default is used (e.g. STANDARD-OUTPUT). 

The iliird argument is a formatting function whicli defaults to NIL. If non-NIL it will be used by 
GDISPATCH to format the object. For example, (GPRINT FOO STANDARD-OUTPUT ' :GfN-FORMAT) 
will use functional format for the top level of FOO no matter what the GAR of foo is. The last four 
arguments can be used to control abbreviation. They are used to set die values of PRINLEVEL, 
PRINLENGTH, PRINENDLINE, and PRINSTARTLINE respectively. If they are omitted, tbcii the current 
bindings of tliese variables are used to control abbreviation, 

GPRINTl object ZtOpt^or\a^ stream fonnat level length endline startUne 

This is exactly like GPRINT except Uiat it corresponds to PRINl instead of PRINT. (Unfortunately, the 
standard Maclisp grind package has already used up the name GPRINl.) 

GPRINC c?/?/Vr/ &opt ion a 1 stream format level length endline startUne 

This is exactly like GPRINT except that it corresponds to PRINC instead of PRINT, 

PL object &optional stream format 

This is an abbreviation for (GPRINT object file Jhrmal NIL NIL NIL NIL). It specifies that the object 
should be printed without abbreviation. It is quite handy 3t top level. 

G FORMAT stream template &rest args 

This is just like FORMAT except Uiat GPRINT is called to do the printing and the templatehas die same 
form as a template for GF. Iw example, (GFORMAT NIL "(*_<*->)" X) creates a string containing X 
printed in functional format at the top level. 

GEXPLODE oo/Vc/ ^optional jhrmat level length 

This is analogous to the function EXPLODE except that it does pretty printing. 

6EXPL0DEC oi/'^cr ^optional format level length 

This is analogous to the function EXPLODEC except that it docs pretty printing. 

PLP&quote &rest args 

This is very similar to GRINDEF but calls GPR INT. llnch arg is eitlier a symbol or a CONS of a symbol 
and a list of speciiic properties to print If it is a symbol then any properties it lias wliich arc in the list 
PLP-PROPLRTIES arc printed. Otherwise, the specified propcrdes are printed. If no <^jr/;5 are supplied 
then PLP is recxccuted on die last set of args it was called on. 

6SET-UP-PRINTER 

Calling this sets up GPRINT as the top level printer, This consists basically of just setting the variable 
PRINl to GPRINTl. 
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^/**N C F template & r e s t args 

This is used to define formatting ftmctions. The structure of tlic template is summarized in a separate 
appendix. Note that unlike GFORMAT tliis does not actually print anyfhing. Rather, it just makes queue 
entries when die formatting function it is in is called by GDISPATCH. The fact that GF is a macro saves 
time by parsing the template at compile time, and producing efficient code to do the formatting. I'his 
does waste space however. It is to your advantage to make each template as short as possible, 

GFUNCTION template 

1 his is an abbreviation for #'( LAMB DA { X) (GF /£'m/?/a/£'X)). 

FORMAT stream format-string drest args 

A new format keyword ^U is defined so that you can call GPRINTl from FORMAT. - : H invokes GPRINC. 
Numeric prc-arguments are taken to be PRINLEVEL, PRINLENGTH, etc. 



/**^., 



/***N 



GPRINT -24- Waters 

Variable Suinniary 

lliis appendix summarizes all of the control variables \yhich can be set by the user in order to control the 
actions of GPRINT. 

PRINLENGTH system clejlned default 

This specifies the maximum length list that will be printed without abbreviation. NIL means infinity. 

miWlV^ll system defined default 

This specifics the maximum depth at which any object will be printed. NIL means infinity. 

PRINSTARTLINE default HIl 

Output is inhibited until the PRiNSTARTLINEth line is reached, NIL is the same as 0. 

PRimmilHE default ^ 

Output is aborted and Ihe printer returns nonnally as soon as die PRtNLNDLINEth line is reached. 

PMHmnGlH default mi 

This specifics the total line length available for printing. If it is NIL, then the printer asks the output 
stream what the line length is. 

MISER-WIDTH ^e/?/w// 40 

M iser mode printout is triggered if there is less than this amount of width available for printing. 

MAJOR 'WIDTH ^('^Z??//// 40 

Loft shifting of logical units will occur if there is less than tliis amount of width available for printing. 

GCHECKRECURSION default T 

] f diis is T then GPR INT checks for circular pointers and abbreviates them appropriately. 

GSHOW-'ERRORS^/(^/;;i///NIL 

Normally, GPRINT does an ERRSET so that no error which occurs during formatting can cause an error 
in GPRINT, [f this is set to T then you will enter the error handler if any error occurs. This is useful for 
debugging. 

Gf'OnCE-mntS defauKl 

]f this is T then tilings are set up so that you get MORE processing all of tlie time. Odierwise, MORE 
piWssing is suppressed if printing is initiated within 7 lijies of the bottom of the screen. 

GSPECIAL-FORMATTERS defaultUlL 

11iis holds a list of formatting functions which are tested for applicability before any other dispatching 
is done. 

G0VERRIDING-LIST-F0RMATTERS^e/(7w//NIL 

This holds a list of formatting functions which are tested for applicability to any list which is being 
printed before any other dispatching is done on it. 
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Z**^ GLIST-FORMATTERS^/e/aw//NIL 

This holds a list of formatting functions which arc tested for applicability to any list which is being 
printed before any other dispatching is done on it unless dispatch was called with a specific suggesting 
of how to format tlic list. (IhQ difference between this and GOVF.RRIDING-LIST-FORMATTERS is that 
these arc applied in fewer places. F'or example, they will not be tested against the list of bound 
variables in a PROG because the fonnat for PROG specifics exactly how this subpart of a PROG should be 
fonnatted.) 

iQf^Onmi property 

If the CAR of a list has a value for diis property, then the value is called as a fonnatting function to 
format the list. (If none of the above cases apply.) 

GAPPLY-fORMAT default :GAPPLY» FORMAT 

Hiis is used as the format for literal LAMBDA applications. 

GFN-FORMAT defcmlf :GFN-FORMAT 

This is used as die default format for function applications. 

6SYMB0L-CAR-F0RMAT default :G1TBL0CK 

This is used as die default format for lists whose CARS are symbols, 

GNON-SYMBOL-CAR-FORMAT default : GITBLOCK 

lliis is used as die default format for lists whose CARs are not symbols. 

/^^ :GFORMAT-SELFmmage 

If an instance, entity, or named-structure is set up so diat it will process diis message type, then it is sent 
a message in order to format itself. It gels one argument (the object itsell) in addition to any arguments 
which are supplied by the message sending mechanism. 

6ARRAY-F0RMATTERSfif^m^//NIL 

This holds a list of formatting functions which wilt be tested for applicability to any array being printed 
which doesn't take a :GFORMAT-vSELF message. 

GHUNK-FORMATTERS default Ull 

This holds a list of formatting functions which will be tested for applicability to any hunk being printed 
which doesn't take a tGFORMAT-SELF message. 

GRIND-MACROEXPANDED defimit NIL 

If diis is T dien MACROMEMOized macros will printed out as diey appear after expansion. Otherwise they 
will be printed out as they appear before expansion. 

PLP-PROPERTIES (if/^zv//(: FUNCTION : VALUE) 

^tliis holds the list of values which die function P LP will print out by default, llie default specifies diat 
only die function value and value should be printed. 



^^ 
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Summary of Formatting Codes 

niis appendix sinnmarizcs the formatting codes which arc available for use in the template supplied to the 
macro GF. The template is a string of single character commands, some of which can be followed by a 
parameter. There arc tliree kinds of parameters: 

n ' Some commands take a number as a parameter. This number should be an integer optionally 
beginning with a "-'* and/or ending with a "/\ Alternately, it can be omitted in which case a 
default value is used, 

/ - Some commands take a function name as a parameter. This name is an arbitrary symbol possibly 
containing " : ". Case does not matter. The symbol must be terminated by a blank. Function name 
parameters cannot be omitted. They have no default values. 

^ - 11m can be used in place of any numeric parameter or any function name parameter. It indicates 
that the next input to GF should be used as the parameter, instead of a literal value. 

llie commands which can be used in a template are divided into several categories. The first set is used to 
parse tlK structure of the arguments to GF so that their parts can be accessed. 

[ ] - This is used to access the internal elements of an item which is a list. The template inside the 
brackets refers to the elements of the list. If the item is not a list, tlien no fonnatting of it, or 
anything inside it, is done. Processing begins by considering each element of this list in turn. As 
soon as tlie list is exhausted, control skips out of the subtcinplate and continues after its end. This is 
done even if there is more stuff left in die subtemplate. Special code is included to deal with the 
possibility of unexpectedly encountering a non-NIL atomic CDR. If this happens it is automatically 
formatted to appear after a ".". [] also produces special code to deal with length abbreviation. 
They only way to get it automatically is to use []. 

. -(Period) This is valid only inside []. U specifies tliat the next item is the whole sublist left to 
process by [] ratlier than its CAR. For example, (GF "[*-..*]" '(1 2)) is the same as 
(GF "*_♦" 1 '(2)). 

Note that when a " . " is used, normal checking for the end of the list in the [] is suppressed. For 
example, (GF "[*^.*^]" ' (l) ) is equivalent to (GF "♦^*_" 1 MIL), llic NIL at the end oftiie 
list is explicitly picked up by the ".", and a blank will be printed at the end. I'his happens even 
though the [] template would normally have terminated right after the first ♦. 

< > - 1liis can only be used directly inside [] (or ( )). It specifics an indefinite repeat block. This is 
used to specify a template fi)r a list of unknown length. 
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llic next set of commands arc used to specify how individual items arc printed out. 

I - Ignore tlie corresponding item. 

'///era/' - Print the indicated literal using PRINC and do not count it as one of die items printed from 
the point of view of length abbreviation. Note that in die literal " ' ' " stands for " ' *\ 

♦ - 1'his specifics that GDISPATCH should be called in order to format the corresponding item. 

%/- This specifies tliat die function/ should be called in order to fonnat die corresponding item. 
(Note if/ is then die argument which is used as the function follows Uic argument whii'i is 
formatted.) 

$/- (Dollar sign) This command specifies diat GDISPATCH should be called in order to fonnat the 
corresponding item, but diat the function/ should be passed to GDISPATCH as a suggestion of how 
to fonnat die item. (Note if/ is dien die argument which is used as die function follows the 
argument which is formaUcd.) The difference between $/ and %/ is that with $/ GDISPATCH gets 
control. As a result, if the item is not a list, or if some function on GOVERfUDING-LIST- 
FORMATTERS formats it, then the function/ will not get used. 

$/"sub!cmplaie/'* - in addition to die name of a function, die parameter to $ can be a literal template 
which is converted into a function to use. (Note that die quotes have to be slashificd in order to 
read in inside a quoted string.) The formatting function produced is compiled out of line. As a 
result, if there is a n format code in it, die aigumcnt to 6F diat this refers to will be compiled out of 
line. In order for diis to work any variables this refers to must be declared special. 

The next commands are used to specify the nested structure of the output (which need not be die same as diat 
of the input). 

{n } - 11iis indicates a substaictural unit in the output. 1^he parameter specifies what indentation to 
use when printing out die items inside die substructure if the substructure cannot be printed on a 
single line. (If die indentation is specified to be zero dien die substructure is not counted as 
increasing die depth from die point of view of depth abbreviation.) The default parameter value is 
calculated as the sum of the lengths of the first diing printed in the substructure, and any literals 
before it and any spaces after it. 

■^^n ' (Plus) Til is specifies a cliange in indentation, llic indentadon level in die current substructure is 
incremented by ;/ which can be negative. Note that dus will not take effect undl the next line. For 
example, the template "(*-«--f2*-*)" docs not increase die indentadon until the fourth item is 
printed while "(*-*+2~*-*) " prints the diird item at an increased indentation. 

( // } " Hiis is a useful abbreviation in the situation where die nested structure of the output is the same 
as the nested structure of the input, and when you want to print parcndicses around die structure. It 
is an abbreviation for {/?'('[ ]')*}. Additionally, if the {n ) is nested more directly inside [] 
than inside $ then it is treated as an abbreviation for $/"{/i' ( ' [ ] ' ) '}/". In other words, if the 
item whose format is being specified by die {n ) was not passed through GDISPATCH for 
dispatching then die $ format code is used to force the list to dispatch through GDISPATCH. This 
prevents the format fiom blowing up when t:he item is not a list. (Note the comment about § inside 
$/" /"above.) 
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llic next set of commands specifics spacing and where and wlien carriage returns should be printed. Note 
that there is actually a complete separation between these two concepts. I'he format codes used above which 
combine the two ideas are abbreviations combining the underlying codes. 

--/? - (Tilde) Print n (default 1) spaces. (Note that spaces are elided if they arc the first or last tiling on a 
line). 

In ' Tab over. Moves to a place where tlie character position relative to the current indentation is 
congruent to zero modulo n, (Does not move at all if it does not have to,) When necessary, a 
default tab size is calculated based on the length of the other items in the substructure. 

A - Do a line break here always. 

! - Same as A. 

N - Do a line break here if required for normal mode printing. I.e. if and only if the structure 
innnediatcly containing this point cannot be printed on a single fine. 

-// - (Minus) Abbj-eviation for "w/N" which is what you iisually want. 

B -j>) a line break here if required for block mode printing. 11iis is die same as N except tliat even if 
the immediately containing structure is being broken up a line break will not be put here as long as 
tlic following structure can be printed on the end of the current line and the prior structure at this 
level was printed on a single line. 

, n - (Comma) Abbreviation for "-/m" wliich is what you usually want. 

; n " (Semicolon) Abbreviation for "~lT/iB" which is what you often want. 

M - Do a line break here if required for miser mode printing. Put a line break here if die containing 
structure will not fit on a single line, and the remaining line width available for printing is less dian 
MISER-WIDTH. 

_/? - (Underscore) Abbreviation ibr "-//M*' which is what you usually want, 

llie next two formatting codes were not discussed above. They arc provided as extra hooks into the 
GPRINTing process. 

&/-The function /is called widi no arguments at Oiis point. Note that function is called during die 
fomiatting process. 

E - When the output routine gets to diis point in prindng, die arg to GF corresponding to the E is 
EVALed (out of line). This is useful for getting information about die state of the printing process. It 
should NOT be used to print anydiing out because the output routine will not realize that anydiing 
was printed and its character position calculations will be wrong. Note that die difference between 
& and E is the time at which die function evaluation occurs. 

The characters SPACE, TAB, CR, and LF are all ignored. Any other character is an error. 



